Update dependency github:yvgude/lean-ctx to v3.11.4 - #2313

v3.11.4

Compare Source

A bugfix release: tool calls that an agent gets almost right are now served instead of refused, edits survive indentation slips, and the Claude Code plugin wakes the agent only once per finished background job. Agent Tools protocol and data formats are unchanged.

Fixed

• Searching a broad directory searches the project instead of failing. ctx_search, ctx_glob and ctx_tree called on ~, / or another directory that contains the session's project now walk the project and say so in the first line of the result. Before, they answered "refusing to scan" and agents repeated the same call. Without a bound project the refusal now names the fix: pass the project directory as path.
• Agents can read their own instruction files. Skills, commands, sub-agent definitions, rules and plans under ~/.claude, ~/.codex/skills and ~/.codex/prompts, ~/.agents/skills, ~/.cursor, ~/.gemini/commands and OpenCode's ~/.config/opencode, plus the global CLAUDE.md, AGENTS.md and GEMINI.md, open read-only on first use. Credentials and settings beside them, such as ~/.codex/auth.json or ~/.claude/.credentials.json, stay closed, and LeanCTX tools cannot write there. A skill linked in from elsewhere below ~ is followed read-only; a link into a protected location or outside ~ is not, and links inside dependency folders such as node_modules are never followed.
• A missing file comes with the file that was meant. ctx_read, ctx_search, ctx_glob and ctx_tree name the existing path when the requested one has a typo, another extension, or was written relative to the wrong directory (src/x.rs for rust/src/x.rs).
• Paths with spaces work when written shell-style. On macOS and Linux a path such as My\ Project/notes.md or '/Users/me/My Project' turned into My/ Project and was reported as missing. Backslash escapes and surrounding quotes are now removed.
• Common argument spellings are accepted. file_path, filePath, file and filename work as path, cmd as command (for MCP calls and lean-ctx call), a path inside a ctx_search queries[] entry scopes that one query, ctx_glob accepts glob for pattern, and ctx_patch replace_all accepts old_string/new_string. A replacement must still be named explicitly, so a missing one is never taken as "delete every match"; two spellings with different values are rejected.
• An edit whose indentation is off still applies. When old_string matches exactly one place in the file at a uniformly different indentation, ctx_edit and ctx_patch (replace_unique) apply it there and shift new_string by the same amount, and say so. Uneven or ambiguous matches still fail with the exact-match error.
• Read modes and glob patterns with small typos work. lines:72:92, lines:72..92, lines 72-92 and a capitalised Full are read as the mode they spell; **.rs and src** are read as **/*.rs and src*/**.
• ctx_read no longer fails with "per-file lock contention". When an earlier read of the same file holds its lock for more than 10 seconds, the read proceeds without it.
• No more "Retry the read" after LeanCTX opened a dependency folder. When a path in a dependency cache or an agent folder is still refused after it was opened read-only, the error now gives the actual reason. lean-ctx call resolves these paths the same way as the MCP server.
• The Claude Code plugin wakes the agent once per finished job. When the agent itself had already read a finished background job with ctx_shell (background_action="status" or "cancel"), the plugin announced the same result again on the next turn, costing a whole extra turn.

Changed

• The token-saving curve in the Claude Code cockpit is drawn true to time and to scale. The x axis now runs from the session's first lean-ctx call to now, the y axis starts at zero, the raw total sits behind "kept out" as a dim envelope, moments in which tokens were kept out are lit, and an axis line shows the session span and the gain of the last ten minutes. Before, one column per sample scaled from the window's lowest value made a single saving look like a cliff.

Upgrade

lean-ctx update                 # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx          # or
npm update -g lean-ctx-bin      # or
brew upgrade lean-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: yvgude/lean-ctx@v3.11.3...v3.11.4

v3.11.3

Compare Source

PathJail opens the home directory by default, the gateway keeps downstream MCP sessions alive between calls, Windows updates and CUDA 13 GPU embeddings work, and Claude Code gets a gateway cockpit. Agent Tools protocol and data formats are unchanged.

Changed

• PathJail opens your whole home directory by default. The default path_jail_scope = home now admits everything below ~ for reading and writing; before, it admitted only paths inside a project, read-only outside the session's project. Protected locations stay closed: every top-level dot entry (~/.ssh, ~/.aws, ~/.config, shell rc files, other agents' ~/.claude, ~/.codex, …), ~/Library, ~/AppData and ~/snap, and everything outside ~. The previous behaviour is the new scope projects (lean-ctx config set path_jail_scope projects), the strictest one stays project. A scope you set yourself is kept; home set explicitly now means the wider scope too. Every installation without its own setting shows a one-time notice on its next interactive command.

Fixed

• Windows: a second update or enable-gpu no longer fails (#​2048). Each update moves the running lean-ctx.exe aside to lean-ctx.old.exe. The process that does this is still running from that file, so it cannot delete it, and the next update refused to start with stale Windows rollback binary exists. The next update now deletes the leftover file. If an old lean-ctx process (an editor's MCP server, a daemon) still runs from it, the file is renamed aside and removed by a later update once that process has exited; only when even that rename fails does the update stop and say which process to close. lean-ctx dev-install uses the same cleanup.
• lean-ctx enable-gpu on the CUDA build it would install says so (#​2048) instead of downloading and reinstalling the same binary. lean-ctx enable-gpu --force still reinstalls it.
• GPU embeddings work with CUDA 13 runtimes (#​2049). onnxruntime-gpu on PyPI is built for CUDA 13 since 1.27, and pip install "onnxruntime-gpu[cuda,cudnn]" installs the CUDA 13 wheels, which put the DLLs into site-packages\nvidia\cu13\bin\x86_64 (Linux: nvidia/cu13/lib). LeanCTX looked only for CUDA 12 libraries (cudart64_12.dll, libcudart.so.12) in the CUDA 12 wheel directories, so lean-ctx embeddings status reported CUDA runtime: not loadable although everything was installed. LeanCTX now reads which CUDA major the selected ONNX Runtime's CUDA provider was built for from the provider's import table and searches and preloads the matching CUDA 12 or CUDA 13 libraries, including the new wheel layout and CUDA_PATH_V13_* toolkits.
• Windows: the CUDA check no longer fails on every machine (#​2049). The check loads onnxruntime_providers_cuda.dll directly; outside ONNX Runtime its initialisation refuses to run, which Windows reports as error 1114 after every dependency has already loaded (Linux reports the same case as a missing Provider_GetHost, which was already handled). embeddings status therefore said not loadable and indexing warned about a CPU fallback while ONNX Runtime was in fact using the GPU, and GPU-sized embedding batches were never used. Error 1114 now counts as loaded; other loader errors show their Windows error code and meaning instead of a bare LoadLibraryExW failed.
• CUDA runtime: OK means the GPU is really used (#​2049). ONNX Runtime loads cudart and cuDNN by name only when a session starts, so a provider DLL that loads (for example through a CUDA toolkit on PATH) could still fall back to CPU without a word. embeddings status now also requires the CUDA runtime and cuDNN to resolve, preloads them before the provider is registered, and names the library that is missing otherwise.
• Clearer CUDA diagnostics on Windows (#​2048, #​2049). Instead of a bare LoadLibraryExW failed, lean-ctx embeddings status lists the missing DLLs and every directory it searched, says when no NVIDIA driver (nvcuda.dll) is installed, and states the CUDA major the provider needs instead of the CUDA version of the ONNX Runtime LeanCTX was compiled against.
• ONNX Runtime and CUDA libraries from more Windows Python installs are found (#​2048): every python.exe on PATH, system-wide installs under %ProgramFiles%\Python3* and C:\Python3*, the Python install manager's %LOCALAPPDATA%\Python\pythoncore-* (the default for Python 3.14) and the Microsoft Store Python, in addition to the per-user installs and active virtual or conda environments.
• lean-ctx embeddings status says which setting chose the embedding model (#​2049): LEAN_CTX_EMBEDDING_MODEL (which overrides the config), [embedding] model in the named config.toml, or the default, plus how to change it.
• Every second gateway call no longer fails with Transport closed (#​2040, reported by @​smollgreymouse). ctx_tools (find, list, call) and gateway compression addons each built their own Tokio runtime per call and dropped it afterwards. A pooled downstream MCP session's transport lives on the runtime that opened it, so the next call got a session whose connection was already gone. All gateway I/O now runs on one runtime that lives as long as the process, so a downstream server is started once and reused across calls.
• The status line shows this conversation's numbers. When several agents run LeanCTX in the same project, the Claude Code status line showed whichever session had written last, so its figures jumped between conversations or stood still. Each session now records the process of the AI client it serves, and the status line reads the session that belongs to its own client.
• Polling a background shell job no longer inflates the session counts. Every ctx_shell status or cancel call for a background job counted as one more tool call and one more command in the session statistics; a single long build polled by an agent could add hundreds. These polls no longer count.

Tool calls that failed although the agent's request was sound, found in the usage telemetry of 3.11.1 and 3.11.2:

• ctx_read answers an empty file, an SVG and a directory. An empty file returned File is empty as an error; it now reads as <path>: empty file (0 bytes). SVG files were rejected as binary; they are XML text and read like source (a real binary behind any extension is still caught by its content). A directory failed with the OS error Is a directory; it now lists its entries.
• ctx_search searches an invalid regex literally. Code text such as foo(, items[0 or fn run(&self is not valid regex and failed the call; it is now searched verbatim, with a one-line note. action=symbol also takes the symbol name from symbol, query or pattern when name is missing.
• ctx_patch infers replace_unique. An edit with old and new text but no op failed with missing 'op'; such an edit can only be replace_unique, at the top level and inside ops[].
• An edit whose result already holds is not an error. ctx_edit (and ctx_patch replace_unique) with identical old and new text, where that text is in the file, reports No change: instead of failing. Text that is absent still fails.
• Dependency source reads on the first call. Reading a file in a language cache registered the cache as a read-only root but still failed the call with "Retry the read"; it now resolves in the same call. The Rust toolchain source (~/.rustup/toolchains), Cargo git dependencies (~/.cargo/git/checkouts) and the Bun, Dart pub and Ruby gem caches are recognized alongside the existing ones. Credential and configuration directories (~/.claude, ~/.codex, ~/.config, ~/.cargo/credentials.toml) stay jailed, and writes into any cache stay denied.
• Usage telemetry counts each tool call once. The daily total of tool calls and failures, and the latency histogram, counted every call twice: once where the call is dispatched and again when its lifecycle finished. The per-tool counts were already right; the totals now match them.
• A failed inline shell command is one error, filed as a failed command. The shell worker also recorded every non-zero exit of a command that finished in the foreground as a LeanCTX-internal error, next to the pipeline's own command entry, and did so even for exit 1 with output (grep, diff, test), which is not an error. The worker now records only background jobs, as command or timeout; inline runs are classified once by the call pipeline.
• Telemetry opt-outs and CI detection reach MCP servers started by Codex. Codex starts MCP servers with only HOME, PATH, USER, LANG and a few more variables, so a server it started could not see DO_NOT_TRACK=1, LEAN_CTX_TELEMETRY=off or the CI markers set in the shell or job around it: an opt-out did not reach the server, and a CI job counted as a local machine. On Linux the server now also reads these few keys, and the runtime-environment markers, from its nearest ancestor processes. Nothing else from their environment is read or kept.
• Containers under cgroup v2 report as container. A container that has no /.dockerenv (containerd, Kubernetes, Podman) and runs under cgroup v2 reported as a local machine. Its overlay root filesystem, the container variable and the Kubernetes service-account directory now mark it too.

Added

• Notices from the LeanCTX team reach the installations they concern. The acknowledgement of a telemetry send can carry up to three short notices, for example "the fix for this ctx_read failure is in 3.11.3". The server picks them by what the batch already reports (version, AI client, OS, runtime environment, a tool that failed), so nothing extra is sent and nobody needs to know who you are. A notice is shown once, on the terminal of the next interactive lean-ctx command, and never in an MCP response: text from a server does not reach the AI model. Only plain text up to 280 characters with an optional link to leanctx.com or the LeanCTX GitHub repository is accepted. With telemetry off, no notices arrive.
• Usage telemetry counts MCP server starts that answered no tool call. Some clients start every configured MCP server, often in a throwaway container, and their agent never calls a tool. Such a start is now counted as an empty session (mcp.session.empty, next to mcp.session), so these starts can be told apart from real sessions.
• Gateway cockpit for Claude Code. The LeanCTX plugin for Claude Code adds a sidebar that shows what passed the gateway in this conversation: which sources Claude saw and at what depth (structure, passage, full file, search, command), the two checks every delivery passed (may it be read, may it leave), the receipts, and the tokens kept out of the context. A line above the prompt pulses while LeanCTX works and shows the handoff from sources to Claude; short overlays mark a finished turn and milestones. The status line below the prompt groups the session as SELECT (files and commands), CONTROL (enforced decisions) and TOKENS (kept out, leaner, cached). It only reads LeanCTX's local session data; nothing is sent anywhere.
• The Claude Code plugin is set up with LeanCTX. When Claude Code is installed, lean-ctx setup, lean-ctx onboard and every update install or refresh the plugin. If you remove it with lean-ctx claude-mod uninstall, it stays removed until you run lean-ctx claude-mod install.

Upgrade

lean-ctx update                 # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx          # or
npm update -g lean-ctx-bin      # or
brew upgrade lean-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: yvgude/lean-ctx@v3.11.2...v3.11.3

v3.11.2

Compare Source

Updater and security hotfix for 3.11.1. Agent Tools protocol, configuration and data formats are unchanged.

Upgrade notes

• Updating from 3.11.0 or 3.11.1 needs one manual step. Their built-in updater stops after downloading and verifying a release with Failed to complete durable update transaction: prepared transaction is missing its integrity digest, and scheduled automatic updates fail the same way. Nothing is changed or damaged: the installed binary keeps running. Install this release once through the channel you installed with — curl -fsSL https://leanctx.com/install.sh | sh, brew upgrade lean-ctx, npm i -g lean-ctx-bin@latest, cargo install lean-ctx --force or your AUR helper — and lean-ctx update and automatic updates work again from then on.
• Windows on 3.11.0 (#​2039): the 3.11.0 updater also needs the external cosign tool and looks for it under that exact name; installing cosign does not help, because its update then stops at the error above. Extract the Windows ZIP of this release over your lean-ctx.exe, or update through npm. From 3.11.1 on, no external tool is needed.

Security

• The home jail scope opens projects, not your home directory. 3.11.1 admitted every path below ~ for reading, so a prompt-injected agent could pull loose personal files (~/Documents/taxes.pdf, ~/Downloads, ~/Desktop) into the model context. A path is now admitted only when a folder between it and ~ holds a project marker (.git, Cargo.toml, package.json, go.mod, pyproject.toml, Makefile, …). Every repository below ~ stays readable; anything else needs lean-ctx allow-path <dir>, and the refusal says so.
• redirect_exclude from an untrusted workspace is withheld (#​2034). Paths in redirect_exclude skip the native-read hook redirect and with it the redaction that path applies. In 3.11.1 a repository's own .lean-ctx.toml could extend the list even when the workspace was not trusted, so a cloned repository could opt its reads out (for example with ["**"]) on hosts where the read redirect is active. Such a list is now ignored with a [SECURITY] warning until you run lean-ctx trust; the global config and LEAN_CTX_HOOK_EXCLUDE still apply.

Fixed

• Codex threads recorded while ChatGPT routing was on stay resumable. Codex stamps model_provider = "leanctx-chatgpt" into every such thread and refuses to resume it once that provider is missing (Model provider 'leanctx-chatgpt' not found). lean-ctx doctor --fix, proxy runs and stale-proxy cleanup deleted the [model_providers.leanctx-chatgpt] block by name, including the direct one users restored by hand. Cleanup now only touches a block that targets the local proxy, and repoints it at https://chatgpt.com/backend-api/codex instead of deleting it; a block aimed anywhere else is kept verbatim and no longer reported as routed or broken.
• ctx_multi_repo action=search without a query says so. While a content policy was active, the call was refused with the cross-project policy message instead of query is required for search.
• No downgrade as "update". Without an explicit version, lean-ctx update and scheduled updates only install a release newer than the running build; a build ahead of GitHub's latest release was offered, and on a schedule installed, the older release. lean-ctx update <version> and --pin still install any version on purpose.
• GitHub API rate limit (#​2037): the updater now sends GITHUB_TOKEN, GH_TOKEN or LEAN_CTX_GITHUB_TOKEN when set (only to api.github.com, without following redirects), raising GitHub's limit from 60 requests per hour per IP address to 5000. An exhausted quota now says so, with the reset time and the fix, instead of http status: 403; a rejected token reports 401 Bad credentials. The background version check uses the same client.
• lean-ctx update and lean-ctx update --rollback complete again. The updater sealed each prepared transaction with its integrity digest when writing it to disk, but then executed the unsealed copy, which the integrity check rejected every time. The updater now executes exactly the sealed transaction it persisted. A new test runs the real prepare → execute → recover path on a stand-in binary.
• macOS: the update signature is applied before the swap. The updater re-signed the installed binary after moving it into place (#​356, so the TCC grant survives), which changed its bytes after the transaction had recorded them; the update then stopped with "active binary does not match prepared target". The staged binary is now signed first, and the receipt records exactly the bytes that are installed; the release manifest and archive digests still record its provenance.
• A reinstall no longer blocks later updates. A failed 3.11.0/3.11.1 run leaves a prepared transaction behind; after a manual reinstall the updater refused every update with "active binary matches neither prepared state". Recovery now recognizes a transaction that a build at least as new as its target has superseded and removes its staged files without touching the binary. Likewise, an update receipt from a different, earlier version no longer refuses updates ("current binary differs from the active receipt"); the updater starts a new receipt from the running binary. A binary that differs from a receipt of the same version is still refused.

Upgrade

lean-ctx update                 # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx          # or
npm update -g lean-ctx-bin      # or
brew upgrade lean-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: yvgude/lean-ctx@v3.11.1...v3.11.2

v3.11.1

Compare Source

Highlights

• Agents can read across all your projects at once: the path jail now admits every project below your home directory for reading by default, while writes stay in the session's own project and ~/.ssh, ~/.aws, ~/.config, other top-level dot directories, ~/Library, ~/AppData and ~/snap stay closed.
• Each agent session binds to the project it was started in. Setup no longer pins one project into an agent's global MCP config, and existing pins are removed.

Upgrade notes

• Path jail scope: the new path_jail_scope setting defaults to "home": reads anywhere below your home directory outside the protected zones; writes only in the session's project, host-declared roots and allow entries. Set lean-ctx config set path_jail_scope project to keep the previous single-project boundary. The setting is global-only; a project-local .lean-ctx.toml cannot change it. With an implausible $HOME (/, a single path component, not owned by you) the scope falls back to project. path_jail = false still disables the jail.
• Protected zones are a hard deny in both scopes: a project root or allow entry that only contains a zone (for example a dotfiles repository at ~) no longer opens ~/.ssh and the like; add an entry inside the zone (lean-ctx allow-path ~/.config/myapp) if a tool must reach it.
• Project pins: earlier lean-ctx setup / doctor --fix runs and MCP-start hook refreshes copied the installing session's LEAN_CTX_PROJECT_ROOT and LEAN_CTX_EXTRA_ROOTS into user-global agent configs (~/.codex/config.toml, ~/.grok/config.toml, global JSON MCP entries), so every later session of that agent opened the same project. The Codex and Grok entries are cleaned on the next agent refresh; lean-ctx doctor reports remaining pins under "Project binding" and lean-ctx doctor --fix removes them line by line, keeping key order and comments (a pin that shares a line with other keys is listed for a manual edit). LEAN_CTX_EXTRA_ROOTS values move into extra_roots; per-project entries in ~/.claude.json are left alone. Restart the agent once afterwards.
• Telemetry: the daily aggregates report more (see Changed), and setup no longer asks: setup and the first interactive command after this update print a three-line notice instead. Turn telemetry off any time with lean-ctx telemetry off, DO_NOT_TRACK=1 or LEAN_CTX_TELEMETRY=off; an explicit opt-out made since 3.11.0 stays in effect, and lean-ctx telemetry show prints the exact payload. What the server keeps, including a keyed network hash and the network operator's public name derived from the connection (never the IP address), and how long, is described at leanctx.com/privacy.

Security

• Agent shells can no longer loosen lean-ctx itself. lean-ctx is on the default shell allowlist, so an agent could run lean-ctx yolo --yes, lean-ctx allow <cmd>, lean-ctx allow-path <dir>, lean-ctx trust, lean-ctx security open, lean-ctx security secrets off or lean-ctx config set <security key> through ctx_shell (or a hook-rewritten Bash call) and then do what the jail or the allowlist had just refused. Those subcommands are now blocked in agent shells with a message to ask the user; listing (--list, status, config show), narrowing (--remove) and tightening (secure, untrust, security secrets on) still run. Run the blocked commands in your own terminal.
• Path jail writes: the new home scope opens other projects for reading only; writes outside the session's project need an explicit lean-ctx allow-path, so an agent in one repository cannot plant another repository's Git hooks or a binary on your PATH.

Added

• lean-ctx allow-path <dir> admits one directory for reading and writing — outside your home directory, a sibling project to edit, or one protected location — effective on the next tool call without a restart. --list shows the jail scope and added directories; --remove takes one out. It refuses /, the home directory and any directory containing it.
• lean-ctx security status shows the active jail scope, and lean-ctx doctor reports global project pins.

Changed

• A refused path names the one command that admits it (lean-ctx allow-path <dir>, offered for the enclosing project) for the user to run in their terminal. The previous hints to open a new IDE window or set an env var that the running server cannot see are gone.
• When a stale LEAN_CTX_PROJECT_ROOT pin is still set and the MCP server starts inside a different real project, the session binds to that project and logs a warning. Host-specific roots (CLAUDE_PROJECT_DIR, workspace folders) keep their precedence.
• Telemetry reports where and how long LeanCTX runs, as coarse ranges. The daily heartbeat adds the runtime environment (local, container, Codespaces, Gitpod, Replit, cloud agent, CI), the installation age (under an hour … 30+ days) and the number of active days in the last 30 (1 … 15+), each as a closed value. They let usage numbers separate people from short-lived agent sandboxes. No machine, account, network or path information is sent. The disclosure lists the new category, so every installation sees the one-time notice again; DO_NOT_TRACK=1, LEAN_CTX_TELEMETRY=off and lean-ctx telemetry off still turn telemetry off.
• The install channel is detected. It was unknown for every installation because no build set it; it now follows the location of the running executable (npm, Homebrew, cargo, PyPI, AUR, release binary). Only the channel name is sent.
• Telemetry reports token savings and per-tool latency. The daily tool aggregate adds the day's total tool-output tokens before and after compression, and each built-in tool's summed latency. Counts only; no content.
• Telemetry includes the daily usage record and why tools fail. The batch carries the last 90 days of the installation's own lean-ctx gain record (operations and tokens before/after compression per day, lifetime totals, month of first use), so usage through shell hooks and before telemetry is counted. Failed tool calls are reported by class (invalid input, not found, permission, policy, timeout, edit conflict, too large, unavailable), together with the five most frequent error messages per tool and day as templates: the client replaces every quoted text, path, file name, number, identifier, URL and e-mail address with a placeholder before anything is sent, and drops a message entirely when no safe wording remains. Shell commands that exit non-zero are now reported as command instead of internal.
• Upgrades turn on telemetry that was only off by the old default. Before 3.11 telemetry was opt-in, so telemetry.enabled = false without a recorded choice is re-enabled once on upgrade, and the one-time notice explains it. An opt-out made since 3.11 (lean-ctx telemetry off, declining in setup, and now also lean-ctx config set telemetry.enabled false) is recorded as explicit and never overridden; DO_NOT_TRACK=1 and LEAN_CTX_TELEMETRY=off always win, and a read-only config is left untouched.
• Telemetry counts which LeanCTX features are used. A daily feature_aggregate reports how often each CLI command runs (lean-ctx pack export → cli.pack.export, graph build, index build-full, telemetry off …) and every graph, BM25 and semantic index build with its failures. Commands and verbs come from a fixed registry; arguments, paths and queries never become part of a code, and hot-path commands (shell hooks, -c, read, grep, statusline) are not counted.
• Telemetry names 21 more AI clients. Cline, Roo Code, Kilo Code, Continue, OpenCode, Goose, Amp, Augment, JetBrains, Warp, Trae, Qwen Code, Crush, Claude Desktop, ChatGPT, LM Studio, Copilot CLI, Visual Studio, Neovim, Emacs and Factory are reported as their own family, and none separates installations used only through the CLI and shell hooks from an unrecognised MCP client (other). The client's name is never sent, and what LeanCTX offers each client over MCP is unchanged.
• Setup no longer asks about telemetry. Setup and the first interactive command after an install or update show a three-line notice instead: telemetry is on, how to turn it off (lean-ctx telemetry off, or enabled = false under [telemetry] in the config.toml it names) and where to see what is sent. The full list stays on lean-ctx telemetry on|off and the payload on lean-ctx telemetry show. An earlier explicit choice is kept.

Fixed

• ctx_shell output capture works in your project. Redirects and tee (> build.log, >> notes.txt, | tee out.txt) were refused everywhere except /tmp, $TMPDIR and write_allow_paths; the project root stayed refused even when listed, and allow_paths / extra_roots were not consulted. Capture may now also go to the session's project and the jail's allow entries. /, ~, its ancestors and read_only_roots are never capture targets; downloads (curl -o, wget, dd of=) keep the scratch-only rule.
• ctx_shell no longer relocates, queues or throttles your builds. Three multi-agent build settings were on by default: agents.shared_cargo_target pointed every cargo build/test run through ctx_shell at <data dir>/build-cache/cargo-target, so ./target kept a stale binary; agents.serialize_build_commands made each build wait for builds from other sessions on the machine; agents.cargo_build_jobs = 3 capped cargo at three jobs. All three are now opt-in (false, false, 0) and documented in the config reference under [agents]. Set them again in config.toml if you relied on the shared cache.
• ctx_shell walk hint judges each invocation on its own (#​2027). A scoped grep -r … tariff followed by a stdin-reading grep in the same command line (…; echo x | grep -c x, | grep -v _test) was treated as a recursive walk of the working directory, so the hint named .claude/worktrees/, node_modules/ or .venv/ although nothing entered them. Only invocations that walk (find, or a grep-like with its own -r/-R) now contribute search roots. With raw: true the hint is no longer appended, matching the verbatim promise.
• lean-ctx update and enable-gpu no longer require a cosign binary. 3.11.0 verified release signatures by running cosign, so on machines without it every binary update and enable-gpu stopped with "cosign is unavailable; refusing unsigned release". The updater now verifies the keyless signature in-process: the certificate must chain to the embedded Sigstore Fulcio root, carry a valid SCT from the Sigstore CT log, name the release workflow at the exact release tag with the GitHub Actions OIDC issuer, and sign the file. When cosign is installed it still runs as an additional check (Rekor transparency log). 3.11.0 installations cannot self-update to this release unless cosign is on PATH (winget install -e --id Sigstore.Cosign, brew install cosign, or a binary from github.com/sigstore/cosign/releases); alternatively reinstall with the install script (macOS/Linux), npm, Homebrew or Cargo, or replace the binary from the release archive.
• Semantic index builds keep their progress. Embeddings were written only after the last chunk, and lean-ctx index build-semantic gave up after 10 minutes, which ended the process and discarded the work — on CPU-only machines and with larger models the index was never built. Builds now save finished files every minute and on errors, Ctrl-C or memory aborts, the next run resumes where the last one stopped, and the CLI waits until the build finishes. index status and doctor report an interrupted build as partial with the resume command.
• ctx_index builds the semantic index in the background. build-semantic and build-full no longer block the tool call, wait for the BM25 index instead of embedding an empty or stale one, and a per-project lock keeps two processes from building the same semantic index at once.
• CLAUDE.md is read in full. Automatic ctx_read modes (and redirected native reads) returned a large CLAUDE.md as a headings-only map, because only SKILL.md, AGENTS.md and a few rule files were treated as instructions. CLAUDE.md, CLAUDE.local.md, GEMINI.md, copilot-instructions.md, .windsurfrules, and documents under .claude/agents/ and .claude/commands/ are now always delivered complete.
• redirect_exclude works again. The key was loaded but never applied, so listing a file there changed nothing. Matching paths (globs on the trailing path components, e.g. CLAUDE.md, *.json, docs/**) now skip the native-read hook redirect and are returned in full by automatic ctx_read modes; LEAN_CTX_HOOK_EXCLUDE (comma-separated) takes precedence, as documented since 2.17.4.
• lean-ctx index build / build-full no longer stop after 5 minutes while graph and BM25 are still building, which ended the process before the index was saved. A build worker that fails unexpectedly now always releases its slot, so the command reports the failure instead of waiting.

Upgrade

lean-ctx update                 # recommended (auto-downloads + refreshes shell hooks)
cargo install lean-ctx          # or
npm update -g lean-ctx-bin      # or
brew upgrade lean-ctx

Note: After upgrading via cargo/npm/brew, run lean-ctx setup to refresh shell aliases. lean-ctx update does this automatically.

Full Changelog: yvgude/lean-ctx@v3.11.0...v3.11.1

v3.11.0

Compare Source

Highlights

• (Preview) Context Gateway admission screens supported reads, derived stores, and supported proxy requests by default, and reports when content was not fully inspected.
• Semantic code views use language-server evidence when available, label uncertain relationships, and avoid linking same-named symbols across language families.
• The optional Claude Code mod shapes large native Bash output, wakes a turn when a watched background job finishes, and restores lean-ctx session context after compaction.
• CLI reads use the same path boundary as MCP reads, command help is side-effect free, and multi-word shell allowlist entries are scoped to their subcommand.
• Anonymous telemetry v2 reports bounded usage aggregates without prompts, source text, paths, commands, or tool arguments, with explicit opt-outs.
• Windows indexing accepts legacy UTF-16 and Windows-1252 text, and Windows CUDA embeddings report missing CUDA 12/cuDNN 9 libraries by name.
• (Preview) The Context Store links one task's plan, delivery and outcome, measures read strategies per workload, and records a learned read policy in shadow unless you opt in.
• lean-ctx pack --limit produces a bounded context bundle, and lean-ctx index why explains why a file is or is not indexed.

Upgrade notes

• Context Gateway (Preview): admission is on by default. Set LEAN_CTX_CONTEXT_GATEWAY=off for one run, or set context_gateway.enabled = false in the global config to disable it persistently. The CLI lean-ctx read path used by shell hooks is outside gateway admission unless a policy pack is active; output redaction still applies.
• Telemetry: v2 is on by default. Setup now asks "Keep anonymous telemetry on? [Y/n]" and lists what is sent; answering n stores an explicit opt-out that every later upgrade keeps. Earlier versions did not store a declined prompt, so an installation that declined before 3.11.0 is on after the upgrade: the first interactive command shows a one-time notice with the full list, and lean-ctx telemetry off turns it off. Disable it any time with DO_NOT_TRACK=1, LEAN_CTX_TELEMETRY=off, or lean-ctx telemetry off; an earlier explicit opt-out remains in effect. CI jobs (CI, GITHUB_ACTIONS, GITLAB_CI, and other common CI markers) never collect or send telemetry; LEAN_CTX_TELEMETRY_IN_CI=1 opts a non-CI machine with such a marker back in. Use lean-ctx telemetry status|show|history|purge-local|delete-remote|reset-id to inspect or manage its payload and ledger.
• Indexes: GRAPH_ENGINE_VERSION and graph INDEX_VERSION are now 7. Existing graph indexes rebuild before use; do not reuse a version 6 graph.
• Semantic mode: semantic_mode = "auto" is the default. It uses running language servers or a live IDE; it does not start servers unless semantic_mode = "eager" is selected in a trusted workspace. Use semantic_mode = "off" to disable semantic enrichment.
• Shell allowlist: multi-word entries now match the exact command unless they end in *. For example, use "git status *" for prefix matching. Set shell_allowlist_subcommand_scoping = false to restore the former base-binary matching.
• Other new defaults: intelligence_runtime.context_policy_apply = false. Each stdio MCP server targets mcp_max_rss_mb = 512 (raise it, or set LEAN_CTX_MCP_MAX_RSS_MB, for very large indexes); mcp_idle_exit_minutes = 0 keeps idle servers running. The engine-context-store-v1 contract and context-gateway-v1 vocabulary are experimental, not stable compatibility promises.
• Claude Code mod: the mod is installed explicitly. When active, set its keep_hook_context option to retain lean-ctx hook context, or shape_native_output to disable native Bash shaping.
• Removed runtime paths: automatic model routing is gone; a leftover proxy.routing.tiers table is ignored and reported by lean-ctx doctor. Rust embedders importing removed internal modules must move to ContextEngine or lean-ctx-sdk.
• Removed shell cache: the opt-in shell output cache was removed; legacy config files still load, but shell_cache_enabled no longer enables cached results.

Security

• lean-ctx -c and -t enforce the shell allowlist under pass-through (#​2004). An agent process can inherit LEAN_CTX_WRAPPED from a wrapped parent; lean-ctx -c then passed the command through raw and skipped the allowlist, so a command ctx_shell blocks ran through the Bash-hook rewrite. Pass-through now skips only compression; the allowlist applies on every route, with the same warn-only rule for an interactive terminal.
• Graph summaries are admitted before indexing. The graph index no longer stores each file's first source line verbatim; summaries pass admission, and files with secret-like paths receive no summary. The graph index version advances to 7.
• Context Gateway admission (Preview). Reads through ctx_read in every mode, plus its shared readers, pass built-in secret, checksum-validated PII, prompt-injection, and classification checks before caching, compression, rendering, or indexing. Search, recovery, and provider paths use admitted content as well. Redactions and withheld reads report reason codes without exposing values; blocking evaluates the original text and withholds content if a redaction leaves a detectable value behind.
  • BM25/trigram indexes, dense snippets, caches, archives and their full-text index, tee/reference results, project knowledge, handoffs, and provider artifacts store admitted text only. Policy changes invalidate affected indexes and caches; recovery is rechecked under the current policy.
  • The local BYOK proxy applies admission to parsed content for supported Anthropic, OpenAI Chat/Responses (including WebSocket), Gemini, and Bedrock request paths, including token-count probes. Provider-sealed fields are not rewritten. Media, malformed bodies, partial scans under max_inspected_bytes, detector timeouts, and invalid custom patterns are reported as not fully inspected; governed/sovereign modes withhold those cases. Restricted content is not sent to a remote model.
  • lean-ctx inspect reports receipt-backed sources, detector coverage, and delivered/withheld outcomes. Receipts include the policy digest and returned-byte digest; tampered receipts are not displayed. context_gateway.hud = auto keeps pure-redaction counts out of the installed Claude Code status line.
• Secret redaction covers more forms. Detection now includes AWS session keys, fine-grained GitHub and GitLab tokens, Anthropic/OpenAI keys, JWTs, Slack/Stripe/npm tokens, private-key blocks, URL-encoded and JSON-escaped values, and secrets split by zero-width or full-width characters. UUIDs and already-masked values are left intact. MCP resources, prompts, lean-ctx call, the agent-tools CLI, and the embed crate use the same output-redaction path.
• Recovery handles are verified before use. Tee, archive, reference-store, and context-ledger handles are checked for resolution, expiry, digest match, and path escape without exposing content; policy refusals are reported as unavailable to the model rather than as broken handles.
• CLI reads and shell allowlists enforce their stated boundaries (#​1901, #​1903, #​1906, #​1419, #​1930).
  • lean-ctx read uses the MCP ctx_read PathJail and secret-path rules. Broad roots are refused unless path_jail = false; relative paths resolve from the current directory. Shell rewrites leave refused reads on the native command, and worktrees under .claude/worktrees are treated as projects.
  • lean-ctx COMMAND --help prints help without running the command; only handlers with verified side-effect-free help receive the flag. upgrade --check only checks.
  • Multi-word allowlist entries such as "git status" match that command only; add a trailing * for a prefix. Binary-specific entries take precedence over project-root auto-allow. lean-ctx doctor reports entries whose meaning changed or is shadowed; the compatibility switch is trust-gated.
  • PowerShell statements are split and checked at their executable commands, including conditions, expressions, and script-block bodies. Only read-only .NET members count as inert; file writers, process starters, and compilers remain blocked. Under bash or zsh, operators and script blocks keep their native meaning; only single inert operands are treated as inert PowerShell.

Added

• mcp_idle_exit_minutes (LEAN_CTX_MCP_IDLE_EXIT_MINUTES, default 0 =
  off) ends a stdio MCP server after that many idle minutes. It is opt-in
  because Codex does not restart exited MCP servers. stdin EOF and a dead
  parent already end the server.
• Gateway proof registry and source planning. A proof registry maps admission cases and bypass checks to their tests, and the release gate can refuse while a proof entry is open. engine context-plan-sources omits caller-supplied sources unrelated to the task even when budget remains; it drops stop words, splits identifiers, and keeps sources related by task terms. lean-ctx inspect shows receipt-derived redaction, withholding, and source-use facts. A local claims catalog records what the release can say and what it does not claim.
• Per-host gateway coverage. lean-ctx doctor reports whether each configured host is enforced, partial, MCP-only/not observable, or unsupported; partial means lean-ctx tools and rewritten shell commands are covered while host-native file tools can bypass admission, and not_observable means MCP-only. lean-ctx inspect shows the same coverage. The generated matrix does not claim observation without an integration that provides it. Claude Code traffic is enforced only with an Anthropic API key; Pro/Max sign-in cannot be proxied. Credential-forwarding journeys for Claude Code /v1/messages and Codex subscription /backend-api/codex/responses show a tool-result credential withheld while the rest of the turn proceeds.
• Claude Code mod (#​1981, #​1986, #​1989, #​1991, #​1997, #​1998). lean-ctx claude-mod install|status|uninstall manages an embedded local plugin for Claude Code 2.1.287 or later; interactive setup offers installation, while non-interactive setup and update only refresh an existing install. MCP is marked always-load, and the mod shapes native Bash output of at least 2,000 characters with fail-open behavior. The shell deny lets Bash(run_in_background) through only when the exact command passes the enforced allowlist; ctx_shape remains an internal hook rather than a listed tool.
  • A configurable set of tool descriptions is front-loaded while the rest is deferred. A watched ctx_shell background job wakes the model once instead of requiring status polling; the mod also answers a bare sleep N while a job is watched.
  • SessionStart/UserPromptSubmit attachments authored by lean-ctx are removed to avoid repeating the same guidance; other hooks and non-lean-ctx text pass through. Use keep_hook_context to opt out. /leanctx shows session-only request, token, ToolSearch, wake, and dropped-context counts; it does not persist them or send telemetry.
  • Before main-conversation compaction, the mod saves session state and asks the summarizer to keep recovery handles and still-reporting job IDs. The first following prompt carries that state once; user compaction instructions and subagent compactions are preserved. Plugin versions include a content hash, and doctor recognizes Claude Code's normalized cache directory name.
• Semantic code intelligence (#​1976, #​1979, #​1983, #​1990, #​1996). Tree-sitter remains the baseline; semantic_mode = auto uses an already-running language server or live IDE to verify uncertain structure, with bounded background refreshes that do not interrupt a backend call. Call edges carry evidence and are shown as verified, resolved, or heuristic; ambiguous callees do not bind to the alphabetically first match. Per-language capability status appears in ctx_graph status and lean-ctx doctor.
  • ctx_impact propagates exact and weaker name-match paths separately. ctx_repomap uses verified graph call edges or caller-scope resolution, and an ambiguous name or vetoed guess does not become a link. Calls are bound within the caller's language family.
  • implements and extends relations are collected where a backend offers them; references are checked on demand by ctx_impact rather than stored as graph edges. TypeScript 7 projects use tsc --lsp --stdio; older projects use typescript-language-server.
  • A VS Code/Cursor/Windsurf extension bridges the editor's existing language features through a per-workspace, token-protected, read-only local navigation endpoint. It does not edit files, start servers, or displace a live server or IDE.
• Context Store (Preview; experimental contract engine-context-store-v1). One task's plan → delivery → outcome lineage, joined from the execution ledger and Decision Receipts and scoped per tenant/project, is shown by lean-ctx inspect --task and lean-ctx engine context-lineage; missing links are listed as gaps rather than filled in.
  • Read-strategy evidence per workload: quality, security (deliveries without full inspection) and runtime friction (re-reads, expansions, failed edits after a compressed read) are measured per task, and anything unmeasured is reported as unmeasured. Available through lean-ctx autopilot evidence, lean-ctx engine context-policy-evidence and lean-ctx eval frontier --save-evidence.
  • lean-ctx autopilot policy status|promote|monitor|rollback keeps a promoted read-strategy policy (active plus last stable) supplied by the optional licensed runtime. Planning records it in shadow only; intelligence_runtime.context_policy_apply = true applies it, and security rules and explicit user choices still take precedence.
  • The context kernel also draws on the BM25 search index and the code graph; it never builds or refreshes an index while planning. Surprise, graph proximity and redundancy are measured from the candidate set.
• lean-ctx pack --limit (#​1885). Writes a deterministic, self-contained XML bundle under a hard character or token cap, ranking files by the task and import graph. It can include current curated knowledge, with that material counted inside the cap; secret-bearing files and secret-like paths are withheld. Emit modes, output files, clipboard, stats, include/ignore globs, and ctx_pack action=bundle are supported. Exit 1 means even the frame could not fit; exit 2 means invalid flags.
• Browser OAuth for HTTP MCP servers (#​1391). lean-ctx addon auth NAME supports OAuth 2.1 discovery, registration, PKCE, loopback redirect, token attachment, and refresh; --status, --logout, and --no-browser are available. Credentials are encrypted per server using the macOS Keychain, Windows Credential Manager, or a Linux 0600 key file. OAuth declarations on stdio servers or alongside an Authorization header are refused.
• lean-ctx index why FILE. Explains which indexing rule included or excluded a file, reports encoding and BM25 chunk/freshness information for eligible files, supports --json, and exits 1 for an excluded file. MCP: ctx_index action=why path=FILE.
• Windows CUDA embeddings. The x86_64 Windows CUDA build is installed and retained by enable-gpu and update. CUDA 12/cuDNN 9 libraries can be loaded from installed pip wheels, the CUDA Toolkit, or the cuDNN installer without changing PATH; CPU-fallback diagnostics name missing DLLs and explain that CUDA 13 alone does not provide CUDA 12 DLLs.
• Clearer ONNX Runtime setup diagnostics. ORT_DYLIB_PATH errors identify whether the variable is absent or malformed and explain process versus MCP configuration scope. Hints identify JSON control characters, quotes, and unexpanded %VAR%, $VAR, or ~ values. lean-ctx embeddings status reports the selected runtime, version check, and execution-provider policy, with platform-specific setup guidance.

Changed

• Bounded memory for long-lived MCP servers. Each stdio MCP server now
  has a per-process RSS target, mcp_max_rss_mb (default 512 MB,
  LEAN_CTX_MCP_MAX_RSS_MB). The guardian uses the lower of it and
  max_ram_percent, which on large machines was several GB per process. A
  Codex app-server that keeps one server per loaded thread therefore no longer
  accumulates ~1 GB instances.
• Idle MCP servers release their caches. After the memory_cleanup TTL
  without a tool call, a server drops its read cache and resident indexes
  without waiting for the next call. A running call or background job keeps
  it busy. The release logs process memory and live heap before and after.
• macOS: the memory guard measures physical footprint. It now uses the
  figure Activity Monitor shows instead of resident size, which leaves out
  pages the memory compressor has taken. An idle server measured 40 MB
  resident while still holding a ~180 MB heap. Footprint is read through
  proc_pid_rusage, which also replaces a ps spawn per sample.
• Quieter, cheaper guardian. Eviction rounds that reclaim nothing back off
  (1 s → 60 s, then a five-minute pause) at every pressure level, not only
  Critical. Sampling stays at one second, so a rise to a higher level still
  evicts at once. Pressure lines log on a level change and at most once a
  minute after that; a baseline above a small cap used to log every second.
• Bundled MCP SDK 1.32.1 in the pi extension (#​2017). `@modelcontextprot

❗ Important

✂ PR body was truncated to here.